Skip to content

docs: prioritize idiomatic TypeSpec over emitter parity in lintdiff migrations - #5446

Merged
Yuchao Yan (msyyc) merged 1 commit into
Azure:feature/lintdiff-migration-newfrom
msyyc:docs/lintdiff-idiomatic-typespec-guidance
Sep 10, 2026
Merged

docs: prioritize idiomatic TypeSpec over emitter parity in lintdiff migrations#5446
Yuchao Yan (msyyc) merged 1 commit into
Azure:feature/lintdiff-migration-newfrom
msyyc:docs/lintdiff-idiomatic-typespec-guidance

Conversation

@msyyc

Copy link
Copy Markdown
Member

Summary

Update only .github/skills/develop-lintdiff-rule/SKILL.md to codify the migration principle settled in PR #5361: prefer idiomatic TypeSpec validation and preserve Swagger parity only where it naturally maps to TypeSpec semantics.

Exact executable Swagger behavior is not the migration contract when reproducing it requires non-idiomatic checks, AutoRest schema formatting/encoding simulation, or handling constructs already invalidated by TypeSpec or Azure rules. The guidance now requires tests showing that added special cases affect valid supported TypeSpec; otherwise, omit the complexity and document the intentional parity gap.

Align coverage classification, the semantic completeness gate, fixture requirements, migration evidence, and review guidance with this priority. Corpus/lintdiff and emission-matrix evidence remain useful research tools, not mandates to reproduce emitter behavior. This follows Timothée Guérin's plain-model/indexer guidance and Catalina Peralta's confirmation of the idiomatic-TypeSpec-first principle.

Scope

Independent documentation-only PR based on and targeting feature/lintdiff-migration-new, not main. No production rules, fixtures, generated corpus data, dependency changes, or release metadata. Chronus excludes Markdown files from change detection.

Validation

  • Prettier check limited to the changed skill document.
  • git diff --check.
  • No repository-wide formatting, build, or tests for this documentation-only change.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@msyyc
Yuchao Yan (msyyc) merged commit 0d9b127 into Azure:feature/lintdiff-migration-new Sep 10, 2026
3 checks passed
@msyyc
Yuchao Yan (msyyc) deleted the docs/lintdiff-idiomatic-typespec-guidance branch September 10, 2026 00:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant